home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Die Speccy' 97
/
Die Speccy' 97.iso
/
amiga_system
/
the_aminet
/
util
/
misc
/
editkeys163.lha
/
EditKeys
/
EditKeys.doc
< prev
next >
Wrap
Text File
|
1995-10-15
|
24KB
|
547 lines
EditKeys v1.63
--------------
⌐ 1991-95 David Kinder
----------------------
Introduction
------------
Around late 1990, I was trying to find a program to allow me to edit the
system keymap files. There were a few that let you put strings on keys, but
none gave total control over all the features of keymaps. So I decided to
write my own editor. I mean, how hard could it be..?
The result is EditKeys, a keymap editing program designed to work under
AmigaDOS 1.3 and higher. EditKeys is written in machine code and compiled
using HiSoft's Devpac v3 assembler, though it should not be that difficult
to compile under other assemblers. EditKeys is freely distributable,
provided that no more is charged than a nominal fee for copying and disk
media. If you want to use a keymap created with EditKeys in a PD or
commercial package then the only condition I impose is that I receive a
credit somewhere in the program or its documentation.
Files
-----
Program - EditKeys
EditKeys.info
Documentation - EditKeys.doc
Disk Libraries - arp.library (must be in LIBS: for AmigaDOS 1.3)
asl.library (must be in LIBS: for AmigaDOS 2.0+)
Source files - EditKeys.s
Graphics.s
xdef.i
xref.i
Tech.Notes
About EditKeys
--------------
EditKeys allows you to edit or create keymap files (They are found in the
Devs/Keymaps/ directory of the boot disk). If you don't know about these
files, then perhaps I should explain.
When you press a key on the Amiga's keyboard, the key press is translated by
the keymap file that the system is using. For instance, British Amigas use
the keymap 'gb'. Different keymaps can be found on the system disks
supplied with your Amiga. They are found in:
AmigaDOS 1.3 Extras1.3:Devs/keymaps/
AmigaDOS 2.0 Extras2.0:Devs/Keymaps/
AmigaDOS 3.0 Storage3.0:Keymaps/
Under AmigaDOS 2.1 and higher keymaps have icons, and are loaded into the
system with the Input prefs editor (or the SetKeyboard command). With
earlier releases, keymaps are loaded with the SetMap program, found in the
System drawer of the boot disk. If you load a keymap different to your
native one, you will find typing some keys gives unexpected results
(especially the non-alphanumeric keys (eg. [,;,# )).
Keymaps can be changed to give more radical results; you could redefine the
numerical keypad to produce alphabetic characters if you wanted to, or you
can configure keys to output strings (useful for disk-menus etc.).
Please note that any changes made using EditKeys do NOT come into effect
until you load the keymap via the system software; only when you select
'Save' in EditKeys is a suitable keymap structure constructed and saved to
disk so that AmigaDOS can use it.
Keymap Specifications
---------------------
At this point, perhaps I should define some of the terms I will use:
Qualifier Key - CTRL, ALT or SHIFT keys. Do not produce output on their
own but qualify the output of other keys (eg Shift-f
produces 'F').
Physical Key - An actual key on the keyboard, the thing that you touch
when you type.
Key - A combination of a physical key and a qualifier, eg q is
a key, as is Shift-q, Alt-q, Shift-Alt-q, etc. Note that
Alt-q is an abreiviation for holding down the ALT key
while tapping the 'q' key.
Keymaps contain quite a lot of information, none of which appears in the user
manuals but appears in the RKM under 'console.device' (Makes sense to put
info about the keyboard in a programmer's manual eh?). Therefore I shall
attempt to briefly describe what is possible.
Keys can be redefined to produce any character when pressed with one of the
qualifiers, and also keys can produce strings of up to 32 characters.
Physical keys with a STRING key on them may not have DEAD or MODIFIABLE keys
on them (see below).
Some keys repeat when held down (eg all alphabetic keys), while others do not
(eg the <RETURN> key). Physical keys which repeat are referred to as
REPEATABLE (fairly obvious). Whether a key repeats or not is controlled by
the keymap. Similarly, the keymap controls whether a key is CAPSABLE or not.
When the 'Caps Lock' light is on, some keys produce their Shifted values (eg
'q'), while the numerical keys produce their normal values.
Some keys are DEAD, while others are MODIFIABLE. For an example of this, open
a CLI window, then hold down ALT while tapping the 'f' key (From now on
abrieviated to Alt-f); nothing happens. Now tap the 'a' key, the result is
an a with an accent over it: 'ß'. The key Alt-f is a DEAD key, while 'a' is a
MODIFIABLE key. When you type Alt-f, the Amiga stores the deadkey, which it
then uses to modify the output of the 'a' key. Not all keys are MODIFIABLE,
Alt-f followed by 'q' just produces 'q'. A physical key with DEAD or
MODIFIABLE keys on it may NOT have STRING keys on it.
There is a further limitation in that those physical keys that are not DEAD
or MODIFIABLE use only 4 bytes for their definition, eg on the 'A' key on
your keyboard there is 'a', 'A', 'µ' and '╞'. However, there are 8 different
permutations of the Shift, Alt and Control qualifiers with the key, so not
every combination of physical key with qualifier can be uniquely defined.
Why didn't Commodore use 8 bytes for each key? (sigh). There is one other
point; if a physical key has definitions for Shift and Alt (and thus
Shift-Alt) then we can configure the key so that the Control qualifier
outputs the value that would appear without the Control key being pressed,
but with bits 6 and 7 cleared (eg Control-c). Confused? You're not the only
one... But playing around with EditKeys should make all this clear (or at
least clearer than it is at present).
It is worth noting before I start on a discussion of EditKeys that once you
have loaded a keymap into the system, you cannot replace it with another
of the same name using SetMap or SetKeyboard. This is because the system
expects keymaps not to change. The solution to this is to use the supplied
'LoadKeymap' command.
The Program
-----------
EditKeys allows you to modify all the above features of a keymap. Keys may be
made DEAD or MODIFIABLE, or have STRING definitions put on them, as well as
being redefined. The program may be started from CLI or Workbench:
From Workbench: Just double click on the program's icon. A file requester
will appear for you to select a keymap to load. Click on
a keymap or 'Cancel'.
From CLI: 1) Just type the program's name, ie
1> EditKeys
The program will attempt to display a file requester
prompting you for a keymap to load. Select a keymap or
click on 'Cancel' to start the program without a keymap
loaded. Or,
2) Pass a keymap name to the program, ie.
EditKeys [<keymap>] [NOMAP]
eg 1> EditKeys gb
or 1> EditKeys NOMAP
You do not need to specify the path of the keymap as
EditKeys will automatically look in DEVS:keymaps/. If
you specify the NOMAP option then EditKeys will start
without loading a keymap. Or,
3) Enter the line
1> EditKeys ?
Which will bring up a template. Entering a further ? will
prompt you with a small help message. Enter a keymap name
or NOMAP (see above).
When the program has loaded it will open a window on the Workbench screen.
In the titlebar is the name of the keymap being edited; below that is a
representation of the A500/A2000/A1200 keyboard with the keymap you chose.
Note that it may appear to you that the keyboard has acquired two extra keys
(one to the right of the left Shift key and the other to the left of the
Return key), as these are not present on the older UK and US Amigas.
Furthermore, the representation of the keymap usually shows what is output
by that key, but for certain keys (eg Esc, Help, Del, F1-F10) I have chosen
to use a little graphic which never changes as this looks better. If you need
to be certain what a key outputs, click on it; its output will be displayed
at the bottom to the EditKeys window.
Qualifier keys (Shift etc.) displayed on the screen work as expected; click
on Shift to see the effect. The program is run using the menus and the five
mode gadgets displayed below the keyboard; each gadget represents a different
aspect of the keymap that can be edited. To choose a mode, simply click on
its gadget. The five modes are:
Keymap - Used to (re)define output of any key
Capsable - Used to determine which keys are capsable
Repeatable - Used to determine which keys repeat
Modifiable - Used to define which keys are modifiable
Deadkeys - Used to define dead keys
I will deal with these sections in increasing order of complexity.
Capsable
--------
As explained above, physical keys can be CAPSABLE or not, and this mode lets
you set this function for each physical key. If the key is highlighed then
that key is capsable; if it is not then the physical key isn't. The qualifier
gadgets are ghosted as they serve no purpose in this mode. Simply click on a
key with the mouse to change it's state.
Repeatable
----------
Basically the same as the above Capsable mode, except that this mode is used
to control which keys are REPEATABLE or not. Works in exactly the same way as
above.
Deadkeys
--------
As expained above, keymaps can contain DEAD keys, and this mode allows you to
set them. Click on a key to make it dead or turn it back to normal. Deadkeys
don't do anything immediately when pressed; thus when you turn a dead back to
normal the key is blank. Since each particular key can be DEAD or not, the
qualifiers are active.
If you make a key dead, and the physical key that key is on already has
another deadkey, then you can make the second deadkey act in the same way as
the first. This isn't too useful, but it's implemented in the CBM keymaps, so
here it is.
Deadkey definitions are stored within the keymap in a completely diffent way
to ordinary keys, so if a physical key has deadkeys on it, then it can be
defined for any combination of qualifiers. As expained earlier, this is not
so for ordinary keys. If you turn a deadkey back to normal and it is the last
deadkey on that physical key, EditKeys will try to resolve this without
destroying any definitions; but if it can't a requester will appear asking
you which definitions you want to get rid of. As a general rule the least
useful set of definitions are those with the Control qualifier, so I'd remove
these first if I were you, but it's your choice. As also explained above, if
a normal key has definitions for Shift, Alt and Shift-Alt, then the Control
key may have a special effect on it - it may clear bits 6&7 of the normaly
output character (eg if you enter Control-c in the string gadget, you get
a capital C in reverse (try it and see)). If it is possible to do this with
the key as we convert it from dead to normal, a requester will appear asking
whether you want this feature or not (As a general rule, in the CBM supplied
keymaps it is turned on for most alphabetic keys).
You can have a maximum of 15 deadkeys, a limitation imposed by the keymap,
not me. 15 should be enough anyway. If you define 15 diffent deadkeys then
all non-dead keys will be ghosted as no more can be defined. Turn a deadkey
back to a normal key to de-ghost all the other keys. Physical keys with
STRING keys on them cannot also have DEAD keys on them; thus all string keys
are ghosted and unselectable. Physical keys with MODIFIABLE keys on them may
also have DEAD keys on them.
Modifiable
----------
This mode works in exactly the same way as the above 'Deadkeys', except that
it allows you to select which keys are MODIFIABLE. Note that I have imposed
an arbitrary limit of 256 modifiable keys in any one keymap, but I doubt that
you would ever need anything like this figure.
Keymap
------
This is the mode you will probably most often use; it allows you to redefine
what each key outputs when pressed. Since this bit is quite complex, I'll
split it into several sections.
Click on the qualifiers and a key to select which key you want to edit. The
selected key will appear highlighted (ie yellow lettering on a black
background), and the cursor in the string gadget below the keyboard will
activate. If you now type something, it will appear in this gadget (since it
is just an Intuition string gadget you can also just click inside it to
re-activate it). There are various types of keys in a keymap (as detailed
previously) so I shall explain how the editing fuctions affect each one:
Deadkeys - Since deadkeys do not output anything themselves but change
the output of other keys, you cannot edit a deadkey and so
such keys are ghosted in this mode. However they are used
in conjuction with modifiable keys (see section below).
Since physical keys with deadkeys on them may also have
keys that work normally (eg Alt-f is a deadkey; Shift-f and
f just work as normal) such keys (eg f) can be edited as
detailed below with the restriction that such keys may NOT
have strings on them.
Ordinary keys - This is the majority of keys, which have no special
features (eg deadkeys). When you click on such a key, the
character output by this key will appear in the little box
to the left of the string gadget below the keymap.
If you enter a single character into the string gadget,
then this will become the character output by the selected
key, and the picture of the keymap will change to reflect
this. As not all combinations of qualifier and physical key
can be uniquely redefined, at certain times (especially if
you edit a key with the Control qualifier (eg Control-q)) a
requester will appear telling you that some definitions
will have to be lost in order to allow your editing, and
giving you the option of aborting or letting EditKeys
remove some of the other definitions on that physical key.
Futhermore, the combination of Shift-Alt-Control-key cannot
be defined at all for ordinary keys. If you try this
EditKeys will tell you that this is not possible.
If you enter more than one character into the string
gadget, EditKeys will convert that key into a STRING type
key (see below).
Modifiable keys - Modifiable keys (eg a) can have their output modified by
deadkeys (eg Alt-f followed by a produces ß). Such keys
can be edited as above except that strings are not
permissible on such keys, thus you can redefine what 'a'
outputs. But what if you want to redefine what Alt-f
followed by 'a' outputs?
If you double click the right mouse button, a requester
titled 'Select deadkey' will appear. This allows you to
choose a deadkey to be used in editing modifiable keys.
The requester has gadgets to accept the current deadkey,
quit without changing anything, or clearing the current
deadkey. To select a deadkey simply type it in at the
keyboard (eg hold down Alt and press f). The text 'A-f'
will appear in the box. Enter another deadkey if you want
to change or press the 'Clear' gadget if you don't want to
use a deadkey anymore, then click 'Use this deadkey'. The
name of the deadkey (eg A-f (which is short for Alt-f))
will now appear in the far left box at the bottom of the
EditKeys window. Now click on a modifiable key (eg a) and
the character output by the combination of the selected
deadkey and the selected modifiable key will appear in the
box to the left of the string gadget (if you are using my
example an 'ß' will appear there). Now when you enter a
character into the string gadget will edit what is output
by the combination of the selected deadkey and the selected
modifiable key. Try it - it is fairly obvious once you're
used to it.
String keys - Lastly, string keys. If you click on a string key (or
change an ordinary key into one by entering more than one
character into the string gadget) then the box to the left
of the string gadget turns yellow. String keys may be
edited in the normal way, except that you may enter up to
32 characters to be output by each key (Some keymaps seem
to have more than this, but the RKM seems to suggest 32 is
the safe limit for the console buffer, so 32 it is).
Note that string keys are usually displayed by EditKeys on
its picture of the keymap as the letters 'STR' where
possible (eg 'Help' is a string key but it always appears
as 'Help' in the little picture as this looks neater).
If you edit a physical key with strings on it so that each
string is only one character, EditKeys will give you the
option of converting that physical key back to an ordinary
key (which saves memory). As usual, EditKeys may have to
remove some definitions to accomodate this; a requester
will appear to warn you if this is the case.
Note that if at any time you want to put a carriage return
in a string, click on the 'Return' gadget (shaped like the
arrow on the Return key, to the right of the <CSI> gadget).
Depending on the AmigaDOS version being used, a little
square box or a reversed 'M' will be added onto the end of
the string in the string gadget. This is useful for eg.
putting common CLI commands on function keys. Thus, if you
put
list*
(where * represents the return character) on F1, then with
this keymap in use, pressing F1 will send a list command
to the CLI as if you had typed it in and pressed <RETURN>.
There is one further point - to the right of the string gadget is a gadget
marked <CSI>. What does this mean? Well, if you click a key such as F1 (with
a standard CBM keymap loaded), you will get something like *0~ where * is a
little square box. This box is used for characters that are not specifically
defined for that font, and in this case the character is $9B hex, which is
known as the 'Control Sequence Inducer', or CSI for short. A CSI is used to
indicate that what follows is not to be output directly but is to be
interpreted by the Amiga to eg. change the text colour etc. There are too
many sequences to document here (they are in the RKM under 'console.device').
Since you can't enter a CSI directly, clicking on the <CSI> gadget will add
a CSI to the current string in the string gadget. The CSI may be the single
character $9B, or the two character sequence $1B followed by $5B (<Esc>[).
The former is used eg. in keymaps to define function keys, while the latter
is used eg. in 'Echo' statements to change the text colour. The type of CSI
provided by the <CSI> gadget is determined in the 'Options' menu (See the
section below on the menus).
The Menus
---------
The remaining functions of EditKeys are accessed through the pull-down
menus. Under AmigaDOS2 or higher, help is available by highlighting a menu
item with the right mouse button, then pressing the 'Help' key. The menu
items available are:
Project Menu
------------
New - Completely clears all information from EditKeys, so allowing you
to create a keymap completely from scratch (but believe me, it's
easier to edit an existing one).
Load - A file requester appears to allow you to select a keymap to load
in. Note that the keymap does not have to be in DEVS:keymaps/ for
to you to be able to load it in.
Save - Saves the current keymap. The keymap is saved to the name of the
keymap last loaded. Note that any previous keymap of the same
name is overwritten (so be carefull!).
Save As - A file requester appears to allow you to select the filename that
you wish the current keymap to be saved to. Again, you do not
need to save to the DEVS:keymaps/ directory, but if you don't,
you won't be able to load the keymap into the system without
using the supplied 'LoadKeymap'.
Test - A window opens into which you can type. The keymap for this
window is that currently being edited by EditKeys, giving a much
easier way to test your new keymap than messing around with
SetMap etc. To close this window type 'quit' on a new line. Make
sure your keymap has 'q','u','i', and 't' defined else you cannot
quit without going back into EditKeys and defining these keys
somewhere. This window is asynchronous to the main window, which
still accepts input while the test window is open. If you
reselect the 'Test' option with the window active, then the
keymap in the test window is updated to that currently in
EditKeys.
Put Char - A requester appears into which you can input the decimal value of
any character, which is then added to the main string gadget.
This is very useful for adding characters which are not mapped
onto the current keymap.
About - Guess.
Sleep - Since the EditKeys window is rather large, you can use this
option to shrink EditKeys out of the way. Under AmigaDOS 1.3,
EditKeys opens a tiny window with just one gadget in it. Click on
this gadget to make EditKeys reopen its main window and resume
normal operations.
Under AmigaDOS2+, this option closes the main EditKeys window
and adds an 'EditKeys' menu item to the Workbench Tools menu. If
you select this item EditKeys will restart.
Quit - Guess... A requester checks that you are sure before quiting (Any
unsaved keymaps will be lost if you quit!).
Options Menu
------------
This menu allows you to alter certain aspects of EditKeys operation.
The available switches are:
One char. CSI - These two options are mutually exclusive and control the
Two char. CSI type of CSI produced by the <CSI> gadget. See the text
about the <CSI> gadget in the 'Keymap' section above.
Create Icons? - Under AmigaDOS 2.1 and higher keymaps now have icons. If
this switch is enabled then the 'Save As' command will
also write out an icon to accompany the keymap, if the
keymap does not already have an icon. The icon is the
standard system icon for keymaps. This option is off by
default.
Well, I think that's it. I think (hope!) the program is easier to use than
this file is to understand, so just use EditKeys and all should become clear.
If for any reason you want to contact me about EditKeys, I can be
contacted via
Internet Email: kinder@teaching.physics.ox.ac.uk
david.kinder@physics.ox.ac.uk
Postal mail: 2, Clwtt Cottages,
Bangor Road,
Gyfelia,
Nr. Wrexham,
Clwyd, LL13 0YL.
ENGLAND.
Thanks to
---------
In no particular order:
HiSoft, Commodore, Oriel, Pink Floyd, The Sisters of Mercy, Curve, and NIN.
History (▓ only applies to AmigaDOS2 or higher.)
------- (│ only applies to AmigaDOS3 or higher.)
v1.0 First release.
v1.1 ▓ Improved appearance under AmigaDOS2.
v1.2 Renamed 'Iconify' menu option to 'Sleep' to reflect that with
AmigaDOS2+ 'Sleep' closes EditKeys down to an item in the
Workbench Tools menu.
▓ Removed need for 'arp.library' under AmigaDOS2+.
v1.3 Added 'Return' gadget.
Modified 'Project' menu; the shortcut for 'Sleep' is now
Right-Amiga-Z (Zzz...).
EditKeys now behaves itself if the default font is not topaz/8.
Added 'CSI Type' menu, <CSI> gadget now produces both types of CSI.
▓ Program now quits with an explanation if 'asl.library' is not
available.
▓ Improved 'Sleep'; if Workbench is not loaded then EditKeys opens
a small window as for AmigaDOS 1.3.
▓ Corrected argument parser routine.
▓ EditKeys window now has a zoom gadget.
▓ Menu help implemented.
v1.4 New 'Project' menu option - 'Test'.
Changed 'CSI Type' menu to 'Options', and added new switch to
the menu - 'Create Icons'.
▓ If Workbench not loaded 'Sleep' shrinks EditKeys to zoomed state.
▓ Menu help for menu headers.
▓ Yes/No requesters now use screen font.
│ Menus have correct new look.
v1.5 ▓ Menu help and file requesters work with zoom gadget.
▓ Menus improved slightly.
If EditKeys is not sure if a file is really a keymap, you are
prompted to make sure that you want to load the file.
v1.6 If 'Create Icons' is selected, a new icon will only be written if
one does not currently exist.
New 'Project' menu option - 'PutChar'.
v1.61 Removed Enforcer hit.
v1.62 Removed more Enforcer hits which occured if there was an error
while loading a keymap at startup.
v1.63 │ Gadgets are ghosted with the correct colours for AmigaDOS3+.
▓ Menu help text corrected.
Changed initial window position.
"Rise and Reverberate"